/*******************************************************************************
 * This file is part of Crunch Network.
 *
 * Crunch Network is free software: you can redistribute it and/or modify it under the
 * terms of the GNU Lesser General Public License as published by the Free Software
 * Foundation, either version 3 of the License, or (at your option) any later version.
 *
 * Crunch Network is distributed in the hope that it will be useful, but WITHOUT ANY
 * WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A
 * PARTICULAR PURPOSE.  See the GNU Lesser General Public License for more details.
 *
 * You should have received a copy of the GNU Lesser General Public License along with
 * Crunch Network.  If not, see <http://www.gnu.org/licenses/>.
 ******************************************************************************/

package com.crunch.network;

/**
 * Provides callbacks for triggering user-specified code when certain network events occur.
 */
public interface NetworkCallbacks {
	/**
	 * This method is used for a number of timing-related tasks, such as measuring ping time or data rates. The method
	 * should return a value representing the number of milliseconds which have elapsed since a fixed point in time.
	 * The fixed point in time can be arbitrary but should not change (e.g. one possible choice is the time since the
	 * device booted).
	 *
	 * @return  the current time in milliseconds.
	 */
	public long getCurrentTimeMs();

	/**
	 * Represents a log message severity level.
	 */
	public enum LogLevel {
		/**
		 * An info message.
		 */
		INFO,

		/**
		 * A warning message.
		 */
		WARNING,

		/**
		 * An error message.
		 */
		ERROR
	}

	/**
	 * Called when a message is available to be written to the log.
	 *
	 * @param   logLevel the severity level of the message.
	 * @param   message the message to write to the log.
	 */
	public void log(LogLevel logLevel, String message);

	/**
	 * Called when a new connection is created. {@code true} should be returned if the connection is to be accepted
	 * and {@code false} should be returned if it is to be discarded.
	 *
	 * @param   connection the new connection.
	 * @param   currentTimeMs the time in milliseconds the new connection was created.
	 * @return  whether this connection should be accepted or discarded.
	 */
	public boolean onReceiveNewConnection(NetworkConnection connection, long currentTimeMs);

	/**
	 * Called when a network connection times out.
	 *
	 * @param   connection the connection that timed out.
	 * @param   currentTimeMs the time in milliseconds the connection timed out.
	 */
	public void onConnectionTimedOut(NetworkConnection connection, long currentTimeMs);

	/**
	 * Called when a packet is received and should be processed.
	 *
	 * @param   connection the connection the packet was received on.
	 * @param   packet the packet to be processed.
	 * @param   currentTimeMs the time in milliseconds the packet was received.
	 */
	public void processPacket(NetworkConnection connection, NetworkPacket packet, long currentTimeMs);

	/**
	 * Called when an acknowledgement is received for a packet.
	 *
	 * @param   connection the connection the packet was acknowledged on.
	 * @param   packetId the ID of the packet that was acknowledged.
	 * @param   currentTimeMs the time in milliseconds the packet was acknowledged.
	 */
	public void onPacketAcknowledged(NetworkConnection connection, int packetId, long currentTimeMs);

	/**
	 * Called when a packet is dropped.
	 *
	 * @param   connection the connection the packet was dropped on.
	 * @param   packetId the ID of the packet that was dropped.
	 * @param   currentTimeMs the time in milliseconds the packet was dropped.
	 */
	public void onPacketDropped(NetworkConnection connection, int packetId, long currentTimeMs);
}
